chrome.userScripts

الوصف

استخدِم واجهة برمجة التطبيقات userScripts لتشغيل النصوص البرمجية للمستخدمين في سياق "النصوص البرمجية للمستخدمين".

الأذونات

userScripts

لاستخدام User Scripts API، chrome.userScripts، أضِف الإذن "userScripts" إلى manifest.json و"host_permissions" للمواقع الإلكترونية التي تريد تشغيل النصوص البرمجية عليها.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

مدى التوفّر

Chrome 120 والإصدارات الأحدث MV3 والإصدارات الأحدث

المفاهيم وطريقة الاستخدام

النص البرمجي للمستخدم هو مقتطف رمز يتم إدخاله في صفحة ويب لتعديل شكلها أو سلوكها. على عكس ميزات الإضافات الأخرى، مثل نصوص برمجة المحتوى وواجهة برمجة التطبيقات chrome.scripting API، تتيح لك User Scripts API تنفيذ رمز عشوائي. تكون واجهة برمجة التطبيقات هذه مطلوبة للإضافات التي تعمل على تشغيل نصوص برمجية يوفّرها المستخدم ولا يمكن إرسالها كجزء من حزمة الإضافة.

تفعيل استخدام واجهة برمجة التطبيقات userScripts

بعد أن تحصل إضافتك على الإذن باستخدام واجهة برمجة التطبيقات userScripts API، على المستخدمين تفعيل زر تبديل محدّد للسماح لإضافة باستخدام واجهة برمجة التطبيقات. يختلف الإعداد المُحدَّد المطلوب للتبديل وسلوك واجهة برمجة التطبيقات عند إيقافها حسب إصدار Chrome.

استخدِم الفحص التالي لتحديد الخيار الذي يحتاج المستخدم إلى تفعيله، مثلاً، أثناء عملية إعداد المستخدم الجديد:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version > 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

توضّح الأقسام التالية مفاتيح التبديل المختلفة وكيفية تفعيلها.

إصدارات Chrome الأقدم من 138 (تبديل الوضع "مطوّر البرامج")

بصفتك مطوّر إضافات، سبق أن فعّلت وضع المطوّر في تثبيت Chrome. على المستخدِمين أيضًا تفعيل "وضع المطوّر".

يمكنك نسخ الخطوات التالية ولصقها في مستندات الإضافة المخصّصة للمستخدمين.

  1. انتقِل إلى صفحة "الإضافات" عن طريق إدخال chrome://extensions في علامة تبويب جديدة. (لا يمكن ربط عناوين URL الخاصة بـ chrome:// عن قصد).

  2. فعِّل "وضع المطوّر" من خلال النقر على مفتاح التبديل بجانب وضع المطوّر.

    صفحة "إضافات Chrome" مع تمييز زر تفعيل وضع المطوّر

    صفحة "الإضافات" (chrome://extensions)

الإصدار 138 من Chrome والإصدارات الأحدث (تفعيل خيار "السماح بنصوص المستخدمين البرمجية")

يمكنك العثور على مفتاح التبديل السماح بنصوص المستخدمين البرمجية في صفحة تفاصيل كل إضافة (على سبيل المثال، chrome://extensions/?id=YOUR_EXTENSION_ID).

يمكنك نسخ التعليمات التالية ولصقها في مستندات الإضافة المخصّصة للمستخدمين:

  1. انتقِل إلى صفحة "الإضافات" عن طريق إدخال chrome://extensions في علامة تبويب جديدة. (لا يمكن ربط عناوين URL الخاصة بـ chrome:// حسب التصميم).
  2. انقر على الزر "التفاصيل" في بطاقة الإضافة للاطّلاع على معلومات مفصّلة عن الإضافة.
  3. انقر على مفتاح التبديل بجانب السماح بنصوص المستخدمين البرمجية.
زرّ السماح بالنصوص البرمجية الخاصة بالمستخدم في صفحة تفاصيل الإضافة
السماح بتفعيل/إيقاف النصوص البرمجية للمستخدم (chrome://extensions/?id=abc...)

التحقّق من توفّر واجهة برمجة التطبيقات

ننصحك بالتحقّق مما يلي لتحديد ما إذا كانت واجهة برمجة التطبيقات userScripts API مفعّلة، لأنّها تعمل في جميع إصدارات Chrome. يحاول هذا التحقّق طلب chrome.userScripts() بطريقة من المفترض أن تنجح دائمًا عندما تكون واجهة برمجة التطبيقات متاحة. إذا ظهرت رسالة خطأ عند إجراء هذا الطلب، يعني ذلك أنّ واجهة برمجة التطبيقات غير متاحة:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

العمل في عوالم معزولة

يمكن تشغيل نصوص المستخدم والمحتوى في عالم منفصل أو في العالم الرئيسي. العالم المعزول هو بيئة تنفيذ لا يمكن للصفحة المستضيفة أو الإضافات الأخرى الوصول إليها. يتيح ذلك لنص برمجي للمستخدم تغيير بيئة JavaScript بدون التأثير في الصفحة المستضافة أو النصوص البرمجية للمستخدم والمحتوى في الإضافات الأخرى. في المقابل، لا تكون نصوص المستخدم (ونصوص المحتوى) مرئية للصفحة المضيفة أو نصوص المستخدم والمحتوى للإضافات الأخرى. يمكن الوصول إلى النصوص البرمجية التي تعمل في العالم الرئيسي من خلال الصفحات المستضافة والإضافات الأخرى، كما تكون مرئية للصفحات المستضافة والإضافات الأخرى. لاختيار المنطقة، أرسِل "USER_SCRIPT" أو "MAIN" عند الاتصال بالرقم userScripts.register().

لضبط سياسة أمان المحتوى في USER_SCRIPT، يُرجى الاتصال على userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

المراسلة

مثل نصوص المحتوى والمستندات التي لا تظهر على الشاشة، تتواصل نصوص المستخدمين مع أجزاء أخرى من الإضافة باستخدام الرسائل (أي أنّه يمكنها استدعاء runtime.sendMessage() وruntime.connect() كما يفعل أي جزء آخر من الإضافة). ومع ذلك، يتم تلقّيها باستخدام معالِجات أحداث مخصّصة (أي أنّها لا تستخدِم onMessage أو onConnect). وتُعرف هذه المعالِجات باسم runtime.onUserScriptMessage وruntime.onUserScriptConnect. تسهِّل المعالِجات المخصّصة عملية تحديد الرسائل الواردة من نصوص المستخدمين البرمجية، والتي تشكّل سياقًا أقل موثوقية.

قبل إرسال رسالة، يجب استدعاء configureWorld() مع ضبط الوسيطة messaging على true. يُرجى العِلم أنّه يمكن تمرير وسيطتَي csp وmessaging في الوقت نفسه.

chrome.userScripts.configureWorld({
  messaging: true
});

تعديلات الإضافات

يتم محو نصوص المستخدمين عند تحديث إحدى الإضافات. يمكنك إضافتها مرة أخرى من خلال تنفيذ رمز في معالِج حدث runtime.onInstalled في عامل خدمة إضافة Chrome. لا تستجِب إلا "update" للسبب الذي تم تمريره إلى دالة الاستدعاء للحدث.

مثال

هذا المثال من نموذج userScript في مستودع العيّنات.

تسجيل نص برمجي

يعرض المثال التالي طلبًا أساسيًا إلى register(). الوسيطة الأولى هي صفيف من العناصر التي تحدّد النصوص البرمجية المطلوب تسجيلها. هناك خيارات أكثر من تلك المعروضة هنا.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

الأنواع

ExecutionWorld

بيئة JavaScript التي يتم تنفيذ نص برمجي للمستخدم فيها

تعداد

‫"MAIN"
يحدّد بيئة تنفيذ نموذج DOM، وهي بيئة التنفيذ المشتركة مع JavaScript للصفحة المستضافة.

‫"USER_SCRIPT"
تُحدِّد بيئة التنفيذ الخاصة بنصوص المستخدم البرمجية وتُستثنى من "سياسة حماية المحتوى في الصفحة".

InjectionResult

الإصدار 135 من Chrome والإصدارات الأحدث

الخصائص

  • documentId

    سلسلة

    المستند المرتبط بالحقنة

  • خطأ

    سلسلة اختيارية

    الخطأ، إن توفّر يستبعد كلّ من الحقلَين error وresult الآخر.

  • frameId

    الرقم

    الإطار المرتبط بالحقنة

  • نتيجة

    أي اختيارية

    نتيجة تنفيذ النص البرمجي

InjectionTarget

الإصدار 135 من Chrome والإصدارات الأحدث

الخصائص

  • allFrames

    منطقي اختياري

    ما إذا كان يجب إدراج النص البرمجي في جميع اللقطات ضمن علامة التبويب القيمة التلقائية هي false. يجب ألا يكون هذا صحيحًا إذا تم تحديد frameIds.

  • documentIds

    سلسلة اختيارية

    أرقام تعريف مستندات محدّدة لإدراجها يجب عدم ضبط هذه القيمة إذا تم ضبط frameIds.

  • frameIds

    number[] اختيارية

    أرقام تعريف اللقطات المحدّدة التي تريد إدراجها

  • tabId

    الرقم

    رقم تعريف علامة التبويب التي سيتمّ إدراجها فيها.

RegisteredUserScript

الخصائص

  • allFrames

    منطقي اختياري

    إذا كانت القيمة صحيحة، سيتمّ إدراجها في كلّ الإطارات، حتى إذا لم يكن الإطار هو الإطار العلوي في علامة التبويب. يتم التحقّق من كل إطار بشكل مستقل للتأكّد من استيفاء متطلبات عنوان URL، ولن يتم إدراجه في الإطارات الفرعية في حال عدم استيفاء متطلبات عنوان URL. القيمة التلقائية هي "خطأ"، ما يعني أنّه تتم مطابقة الإطار العلوي فقط.

  • excludeGlobs

    سلسلة اختيارية

    تُحدِّد أنماط العناصر النائبة للصفحات التي لن يتم إدراج نص برمجي المستخدم فيها.

  • excludeMatches

    سلسلة اختيارية

    تستبعد الصفحات التي سيتم إدراج نص المستخدم البرمجي هذا فيها. اطّلِع على أنماط المطابقة للحصول على مزيد من التفاصيل حول بنية هذه السلاسل.

  • id

    سلسلة

    رقم تعريف نص المستخدم المحدّد في طلب البيانات من واجهة برمجة التطبيقات يجب ألا تبدأ هذه السمة بشرطة سفلية "_" لأنّها محجوزة كبادئة لأرقام تعريف النصوص البرمجية التي تم إنشاؤها.

  • includeGlobs

    سلسلة اختيارية

    تُحدِّد أنماط العناصر النائبة للصفحات التي سيتم إدراج نص برمجي المستخدِم فيها.

  • js

    ScriptSource[] اختياري

    قائمة عناصر ScriptSource التي تحدّد مصادر النصوص البرمجية التي سيتم إدراجها في الصفحات المطابقة يجب تحديد هذه السمة لدالة ${ref:register}، ويجب أن تكون صفيفًا غير فارغ عند تحديدها.

  • فلتر مطابق لـ

    سلسلة اختيارية

    تُحدِّد الصفحات التي سيتم إدراج نص برمجي للمستخدِم فيها. اطّلِع على أنماط المطابقة للحصول على مزيد من التفاصيل حول بنية هذه السلاسل. يجب تحديد هذه السمة لـ ${ref:register}.

  • runAt

    ‫RunAt اختيارية

    تحدد هذه السمة وقت إدخال ملفات JavaScript في صفحة الويب. القيمة المفضّلة والتلقائية هي document_idle.

  • العالم

    ExecutionWorld اختياري

    بيئة تنفيذ JavaScript لتشغيل النص البرمجي القيمة التلقائية هي `USER_SCRIPT`.

  • worldId

    سلسلة اختيارية

    الإصدار 133 من Chrome والإصدارات الأحدث

    تُحدِّد رقم تعريف عالمي لنص برمجي للمستخدِم لتنفيذه. في حال حذف هذا العنصر، سيتم تنفيذ النص البرمجي في سياق النص البرمجي التلقائي للمستخدم. لا يكون هذا الحقل صالحًا إلا إذا تم حذف world أو إذا كانت قيمته USER_SCRIPT. إنّ القيم التي تحتوي على شرط سفلية (_) في البداية محجوزة.

ScriptSource

الخصائص

  • رمز

    سلسلة اختيارية

    سلسلة تحتوي على رمز JavaScript المطلوب إدراجه يجب تحديد سمة واحدة فقط من file أو code.

  • ملف

    سلسلة اختيارية

    مسار ملف JavaScript المطلوب إدخاله بالنسبة إلى الدليل الجذر للإضافة. يجب تحديد سمة واحدة فقط من file أو code.

UserScriptFilter

الخصائص

  • ids

    سلسلة اختيارية

    لا يعرض getScripts سوى النصوص البرمجية التي تحتوي على المعرّفات المحدّدة في هذه القائمة.

UserScriptInjection

الإصدار 135 من Chrome والإصدارات الأحدث

الخصائص

  • injectImmediately

    منطقي اختياري

    ما إذا كان يجب بدء عملية الإدراج في الهدف في أقرب وقت ممكن. يُرجى العِلم أنّ هذا لا يضمن أن يتمّ الحقن قبل تحميل الصفحة، لأنّه قد يكون قد تم تحميل الصفحة قبل أن يصل النص البرمجي إلى الهدف.

  • قائمة عناصر ScriptSource التي تحدّد مصادر النصوص البرمجية التي سيتم إدراجها في الهدف

  • الاستهداف

    InjectionTarget

    تفاصيل تحدّد الهدف الذي سيتمّ فيه إدخال النصّ البرمجي

  • العالم

    ExecutionWorld اختياري

    "عالم" JavaScript لتشغيل النص البرمجي فيه القيمة التلقائية هي USER_SCRIPT.

  • worldId

    سلسلة اختيارية

    تُحدِّد رقم تعريف بيئة نص المستخدم الذي سيتم تنفيذه فيه. في حال حذف هذا العنصر، سيتم تنفيذ النص البرمجي في سياق النص البرمجي التلقائي للمستخدم. لا يكون هذا الحقل صالحًا إلا إذا تم حذف world أو إذا كانت قيمته USER_SCRIPT. إنّ القيم التي تحتوي على شرط سفلية (_) في البداية محجوزة.

WorldProperties

الخصائص

  • csp

    سلسلة اختيارية

    تحدّد خدمة إدارة المحتوى الآمن (CSP) على مستوى العالم. الإعداد التلقائي هو خدمة إدارة الخدمات في `ISOLATED`.

  • المراسلة

    منطقي اختياري

    يحدِّد ما إذا كانت واجهات برمجة تطبيقات المراسلة معروضة. القيمة التلقائية هي false.

  • worldId

    سلسلة اختيارية

    الإصدار 133 من Chrome والإصدارات الأحدث

    تُحدِّد معرّف عالم نص برمجي محدّد للمستخدم المطلوب تعديله. في حال عدم توفيرها، يتم تعديل سمات عالم نص المستخدم التلقائي. إنّ القيم التي تحتوي على شرط سفلية (_) في البداية محجوزة.

الطُرق

configureWorld()

الوعد 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

لضبط بيئة تنفيذ `USER_SCRIPT`

المعلمات

  • المواقع

    WorldProperties

    يحتوي على إعدادات بيئة النص البرمجي للمستخدم.

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

execute()

الوعد Chrome 135 والإصدارات الأحدث 
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

يتيح هذا الإذن إدخال نص برمجي في سياق مستهدَف. سيتم تشغيل النص البرمجي تلقائيًا في document_idle، أو على الفور إذا سبق أن تم تحميل الصفحة. في حال ضبط السمة injectImmediately، سيتمّ إدراج النص البرمجي بدون انتظار، حتى إذا لم ينتهِ تحميل الصفحة. إذا تم تقييم النص البرمجي على أنّه وعد، سينتظر المتصفّح استقرار الوعد وعرض القيمة الناتجة.

المعلمات

المرتجعات

  • Promise<InjectionResult[]>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

getScripts()

الوعد 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

تعرِض هذه الدالة جميع نصوص المستخدم المسجَّلة ديناميكيًا لهذه الإضافة.

المعلمات

  • تصفية

    ‫UserScriptFilter اختياري

    في حال تحديدها، لا تعرض هذه الطريقة سوى نصوص المستخدم التي تتطابق معها.

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (scripts: RegisteredUserScript[]) => void

المرتجعات

  • تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

getWorldConfigurations()

الوعد Chrome 133 والإصدارات الأحدث 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

يستردّ جميع إعدادات البلدان المسجّلة.

المعلمات

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (worlds: WorldProperties[]) => void

المرتجعات

  • Promise<WorldProperties[]>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

register()

الوعد 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

تُسجِّل نصًا برمجيًا واحدًا أو أكثر للمستخدم لهذه الإضافة.

المعلمات

  • نصوص برمجية

    RegisteredUserScript[]

    يحتوي على قائمة بنصوص المستخدمين التي يجب تسجيلها.

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

resetWorldConfiguration()

الوعد الإصدار 133 من Chrome والإصدارات الأحدث 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

تُعيد ضبط الإعدادات لعالم نص برمجي للمستخدم. وستستخدم أي نصوص برمجية يتم إدراجها في العالم باستخدام المعرّف المحدّد الإعدادات التلقائية للعالم.

المعلمات

  • worldId

    سلسلة اختيارية

    رقم تعريف بيئة نص المستخدم المطلوب إعادة ضبطها. في حال حذف هذا الحقل، تتم إعادة ضبط الإعدادات التلقائية للعالم.

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

unregister()

الوعد 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

تؤدي هذه القيمة إلى إلغاء تسجيل جميع النصوص البرمجية للمستخدمين المسجَّلة ديناميكيًا لهذه الإضافة.

المعلمات

  • تصفية

    ‫UserScriptFilter اختياري

    في حال تحديدها، لا تُلغي هذه الطريقة سوى نصوص المستخدم التي تتطابق معها.

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى الدالة المُعاد الاتصال بها.

update()

الوعد 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

تعديل نص برمجي واحد أو أكثر للمستخدمين لهذه الإضافة

المعلمات

  • نصوص برمجية

    RegisteredUserScript[]

    يحتوي على قائمة بنصوص المستخدمين التي يجب تعديلها. لا يتم تعديل سمة للنص البرمجي الحالي إلا إذا تم تحديدها في هذا العنصر. إذا حدثت أخطاء أثناء تحليل النصوص البرمجية أو التحقّق من صحة الملفات، أو إذا لم تتطابق المعرّفات المحدّدة مع نص برمجي مسجّل بالكامل، لن يتم تعديل أي نصوص برمجية.

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • Promise<void>

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير طلبات الاستدعاء لأجل التوافق مع الإصدارات القديمة. ولا يمكنك استخدام كليهما في طلب الدالة نفسه. يتم حلّ الوعد بالنوع نفسه الذي يتم تمريره إلى دالة الاستدعاء.